home *** CD-ROM | disk | FTP | other *** search
/ The 640 MEG Shareware Studio 2 / The 640 Meg Shareware Studio CD-ROM Volume II (Data Express)(1993).ISO / basic / qbredir.zip / QBREDIR.DOC < prev    next >
Text File  |  1992-03-02  |  8KB  |  204 lines
  1.  
  2.  
  3.                         QBREDIRECT
  4.  
  5.                         By Peter R. Barnes
  6.  
  7.                         March, 1992
  8.  
  9.  
  10.  
  11.  
  12.  
  13. WHAT IS QBREDIRECT?
  14.  
  15. This utility module allows QuickBasic programmers to display the
  16. redirected output of an executed program simultaneously to the screen
  17. as it is sent to the redirection target (usually, a file).  Why would
  18. you want to do this?  The best reason I can think of would be the
  19. common situation where you want to record some information to a file
  20. for later action or review, but need to keep the user informed of the
  21. current status.  The sample program REDTEST.BAS, included here, is a
  22. good example.
  23.  
  24. Let's say your program wants to format a user disk, and keep track of
  25. the total bytes available on that disk.  One simple way to accomplish
  26. this task is to do something like:
  27.  
  28.                SHELL "format a: >fmt.txt"
  29.  
  30. At the end of the formatting process, DOS will tell you how much space
  31. is available on the disk by outputting:
  32.  
  33.                xxxxxxx bytes free
  34.  
  35. Now, with redirection being used, that number would be written to your
  36. redirection target file, fmt.txt, where you could obtain it by opening
  37. and reading the file via Basic.  But there are two obstacles to doing
  38. this.  As soon as DOS receives a command to format, it puts out a
  39. message:
  40.  
  41.                Insert disk in Drive A:
  42.                Press ENTER when ready
  43.  
  44. If output is redirected, that message is sent to the target file, too,
  45. so the user never sees it.  Meanwhile, DOS waits for the user to press
  46. ENTER -- and DOS is very patient, it will wait a !!!LONG!!! time.  To
  47. make things worse, DOS does the same thing after it outputs the "bytes
  48. free" message, by asking:
  49.  
  50.                FORMAT ANOTHER (Y/N)?
  51.  
  52. Again, DOS will expect an answer, but only our redirection file knows
  53. the question!
  54.  
  55. Of course, you could use a library that provides routines to do this
  56. task, or some other fancy tricks such as using redirected input, but
  57. why bother, when DOS will do it for you?  All you REALLY want to do is
  58. capture the output, and redirection does a fine job of accomplishing
  59. that task.  The only problem is that DOS likes to do things its' way;
  60. it will not allow you to see what's going on when redirection is used,
  61. like the example we are considering here.
  62.  
  63. The QBREDIR module solves the problem by tapping into the DOS Interrupt
  64. Services interrupt 21 routine.  Whenever DOS does just about anything
  65. related to the outside world, it uses interrupt 21 to do the job.  Our
  66. module intercepts calls to this interrupt to check for DOS output to a
  67. file.  If that is the case, QBREDIR duplicates the information and
  68. sends it to the screen so that the user can see what is going on.  Your
  69. program controls this action merely by setting or zeroing a flag
  70. variable that you pass to QBREDIR when you install the module in
  71. memory.  By polling this flag, QBREDIR determines what action will
  72. occur when output is redirected.
  73.  
  74.  
  75.  
  76. THE LEGAL STUFF
  77.  
  78. This program is released to the public domain, meaning you may use it
  79. for any purpose you desire.  Nor will I be responsible for anything
  80. that happens when you use it, period.  The program is based on the
  81. public-domain routine REDVIEW.COM, written by Alexander Novy and Petr
  82. Horak of the University of Prague in Czechoslovakia, and I have revised
  83. it to work with QuickBasic Ver. 4.5.  I did this only as an exercise
  84. for myself in assembly level programming, and I thought someone else
  85. may find it useful.
  86.  
  87.  
  88.  
  89. RESTRICTIONS ON USING QBREDIR
  90.  
  91. Because this routine installs a custom interrupt handler in your PC
  92. when it is run, it must be treated with care, in that you must always
  93. remember to remove it from memory after you have installed it.
  94. Furthermore, the routine reads a value from a memory location that was
  95. identified as your flag variable when the routine was installed in
  96. memory;  however, we all know that QuickBasic occasionally likes to
  97. move variables around whenever it feels the urge, so you may observe a
  98. problem that indicates that QBREDIR has lost track of your flag
  99. variable.  All I can suggest in those cases is that you use a liberal
  100. sprinkling of DEFSEG, VARSEG, and VARPTR statements to verify what is
  101. happening.  I don't think it will happen, though, unless your program
  102. is REALLY long, or it uses lots of dynamic, redimensioned arrays, or a
  103. ton of concatenated string variables.
  104.  
  105. You can avoid the problem by calling the QFRedSet subroutine just
  106. before the redirection is to occur, because that will pass the current
  107. address of your flag variable to QBREDIR.  A call to QFRedSet, after
  108. the initial call to install the handler routine and prior to any call
  109. to QFRedOff, merely updates the location of your flag variable for the
  110. handler.
  111.  
  112. Note that you cannot use QBREDIR in the QuickBasic Editor environment,
  113. because redirection has no effect when you are in the editor environment.
  114. Also remember that, when redirection is in effect, QBREDIR only displays
  115. redirected output information; in our "format" example above, this means 
  116. that our routine will display the "FORMAT ANOTHER (Y/N)?" message, but 
  117. it will NOT echo the "Y" or "N" keystroke that the user types to answer 
  118. the prompt, because that is handled by a different interrupt (the 
  119. keystroke will appear in the redirection file, however).  
  120.  
  121.  
  122.  
  123.  
  124. HOW TO USE QBREDIR
  125.  
  126. With those restrictions in mind, the routine is easy to use.  When you
  127. want to enable screen display of redirected output, you call the
  128. installation routine, passing to it the address of the integer variable
  129. that will activate the display:
  130.  
  131.                 CALL QFRedSet (YourFlagVariable%)
  132.  
  133. Thereafter, whenever you want to turn display of redirected output on
  134. or off, just set your variable to zero (off) or 1 (on).  The interrupt
  135. handler routine will look at this flag to determine its' action.
  136.  
  137. When it is time to end your program, or if you just want to uninstall
  138. the handler routine from memory, you simply:
  139.  
  140.                 CALL QFRedOff
  141.  
  142. Thereafter, all redirected output will be processed in the usual DOS
  143. manner.  Be sure to ALWAYS do this call before you end your program, OR
  144. YOU WILL SURELY LOCK UP YOUR COMPUTER AFTER YOUR PROGRAM ENDS.
  145.  
  146. Examine the source code in REDTEST.BAS to get an idea how easy it is to
  147. set up and use this utility.  Just be sure to link your program with
  148. the module QBREDIR.OBJ when you make your executable file:
  149.  
  150.                 LINK /[your options] YOURPROG + QBREDIR;
  151.  
  152.  
  153.  
  154. FILES INCLUDED WITH THIS PROGRAM
  155.  
  156. You should have the following files in this package:
  157.  
  158.         QBREDIR.OBJ     --      This is the Object module you link with
  159.                                 your program to enable redirection
  160.                                 display
  161.  
  162.         QBREDIR.ASM     --      The Assembly listing used to make the
  163.                                 Object module.  It is in tutorial form
  164.                                 because that was its original purpose.
  165.  
  166.         QBREDIR.DOC     --      This documentation file
  167.  
  168.         QBREDIR.LST     --      A listing file produced by TASM during
  169.                                 compilation, included here for those
  170.                                 interested
  171.  
  172.         REDTEST.BAS     --      Source code for a simple demonstration
  173.                                 of the handler routines
  174.  
  175.         REDTEST.EXE     --      Executable form of the demo program
  176.  
  177.  
  178.  
  179.  
  180. "REGISTRATION"
  181.  
  182. If you like this routine (or even if you don't), I would enjoy hearing
  183. your comments about it. Send them to:
  184.  
  185.                         Peter R. Barnes
  186.                         9116 Saddlebow Dr.
  187.                         Brentwood, Tn. 37027
  188.  
  189. or you can leave a message in the I-LINK Quick Basic Conference on any
  190. BBS system, and I will pick it up.  I am usually checking on to the
  191. following excellent boards every day or so:
  192.  
  193.                 DATAWORLD       615/966 3574    'Tennessee's Finest!
  194.  
  195.                 HACKER CENTRAL  201/334 2555
  196.  
  197.                 COMPUDATA       609/232 1245
  198.  
  199.  
  200. Remember the Quick Basic Motto:
  201.  
  202.                 ANYTHING C CAN DO, WE CAN DO BETTER!
  203.  
  204.